Programming

Variables	

The standard Basic variable types of Integer, String and Float are available for normal use within a program.

Integer
a 32 bit signed Integer

String  [len]
a Basic string implemented as a 16 bit length followed by the string itself.
Only fixed length strings are supported in this version.

Float
an 80 bit floating point number implemented using the Apple SANE libraries.

Additionally, Pascal type variables may be used for communication with the Macintosh Toolbox.

Byte
an 8 bit unsigned value

Word
a 16 bit signed value

Char [len]
a fixed length string of characters

Str255 [len]
a pascal string consisting of an 8 bit length followed by the string.

A structure type construct is provided for toolbox communication and for creating structured records for use in Random file access. (See GET and PUT).

Variables may have a LOCAL or GLOBAL scope. The examples below demonstrate the usage of the different variable types available.

Global Myint As Integer
Local Mystr As String [30]               .. maximum length=30 characters.
Global Mybyte As Byte
Local Myword As Word
Global Mychar As Char [20]              .. fixed length= 20 characters.
Local Mypstring As Str255 [10]       .. maximum length=10 characters.

Local Mystruct As Structure
        Local Myint As Integer
        Local Mystr As String [10]
Endstruct 

Arrays	

Arrays may have up to 3 dimensions in this version of the compiler and are dynamic in the sense that the size of an array can be changed at any time.
Arrays are given an initial dimension when declared with the GLOBAL or LOCAL statements and are resized with the REDIM statement.
The contents of an array may be saved and subsequently loaded between program invocations using the ARRAYLOAD and ARRAYSAVE statements. The contents of saved arrays are stored at DATA type resources in the applications resource file.
The maximum number of elements which can be stored in an array is 65000.

Arithmetic Functions and Commands	

The following arithmetic functions are supported:

        +        Add
        -        Subtract or unary minus
        *        Multiply
        /        Divide

Additionally, the ADD and SUB commands may be used where an integer expression needs to be add to or subtracted from a variable and the INC and DEC commands provide a quick way to Increment or Decrement the value of an integer variable.  

Logical Operators	

The logical operators AND, OR, NOT and XOR (Exclusive OR) are available for use in arithmetic and conditional expressions.
A logical TRUE yields a result of -1 whereas a logical FALSE yields a result of zero.

Comparison Functions	

Comparison functions, together with Logical Operators, resolve an expression down to a TRUE or FALSE value. The following comparison functions are implemented :-

        >                Greater than
        <                Less than
        =                Equal to
        <> or !=       Not equal to
        >= or =>      Greater than or equal to
        <= or =<      Less than or equal to

Program Flow	

Several standard Basic constructs are available for controlling program flow :

The FOR / NEXT loop which steps through the loop a fixed number of times changing the value of a variable each time it passes through the loop.

FOR <variable name> = <start expression> TO <end expression> [STEP <expression>]
        statements
NEXT

The variable is initially set to <start expression> and each time through the loop, the STEP <expression> is added to it until it reaches the value of the ,end expression>. The STEP parameter defaults to 1.

The REPEAT construct loops until a condition is met.

        REPEAT
            statements
        UNTIL <conditional expression>

REPEAT always executes the statements between the REPEAT and UNTIL at least once.

The WHILE contruct also loops until a condition is met but in this case the condition is tested at the beginning of the loop.

        WHILE <conditional expression>
            statements
        WEND

The DO CASE construct allows multiple conditions to be tested and different actions to be taken according to the results..

        DO CASE
                CASE <conditional expression>
                    statements
                    [BREAK}
                CASE ......
                DEFAULT
                    statements
        ENDCASE

The conditional expression after each CASE statement is evaluated and program flow continues if the condition is found to be true. The BREAK statement forces execution to continue after the ENDCASE statement. The DEFAULT condition is met if no BREAK statements are encountered.

The IF / THEN / ELSE / ENDIF construct is implemented.

        IF <conditional expression> [THEN]
                statements
        [ELSE]
                statements
        ENDIF

The THEN keyword is optional and is retained for compatibility.

The GOTO keyword is also supported for completeness.

        GOTO <label>

A label may be any string of characters terminated by a colon. The label to which a GOTO is referenced must be in the same function or procedure as the GOTO statement itself.

Procedures / Functions	

Procedures implement subroutines within a program. A procedure may be invoked using the DO <procname> statement. i.e.

        DO <procname> [(<parameter>,<parameter> ....)]

The parameters with the PROCEDURE statement must match those passed by the DO statement in both number and data type although, of course, the names may be different. Each parameter is further described by a PARAMETER statement. For example:

GLOBAL Mystr AS STRING [30]
GLOBAL Myint AS INTEGER
        DO Myproc(Mystr,Myint)
        .........
        END

PROCEDURE Myproc(Parm1,Parm2)
PARAMETER Parm1 AS STRING
PARAMETER Parm2 AS INTEGER
        .........
RETURN

Functions are similar to procedures except that they return data to the caller. Example:

GLOBAL Mystr AS STRING [30]
GLOBAL Myint AS INTEGER

        Myint=Myfunc(Mystr)
        .......
        END

FUNCTION Myfunc(Parm1) RETURNING INTEGER
PARAMETER Parm1 AS STRING
LOCAL Retval As INTEGER
        Retval=VAL(Parm1)
        .....
RETURN Retval

Local variables may be used for temporary storage in either Functions or Procedures. There contents are lost whenever the Function or Procedure terminates.

By default, all data passed to functions and procedures is passed by Value. It is possible to pass data by Reference allowing the function or procedure to change its value.

Global Myint As INTEGER
        Myint=1
        DO MyProc(BYREF(Myint)
        PRINT Myint
        END

Procedure Myproc(Parm1)
PARAMETER Parm1 As INTEGER BYREF
        Parm1=Parm1*2
RETURN

In the above example, 2 would be printed on the console.

Normally, a function or procedure is only visible with the program module which it resides. To make a function or procedure globally visible across all program modules, the PUBLIC keyword is used.

PROCEDURE Myproc(Parm1) PUBLIC
FUNCTION Myfunc(Parm1) RETURNING STRING PUBLIC

Procedures which trap events, eg.
        Procedure MyForm.MyControl.Click()
are treated as Public by default.

Disk I/O	

Disk files may be opened for Input, Output, Append or Random. 
In Input mode data is read sequentially from the beginning of the file until the end. 
In Output mode data is written from the beginning of the file with the file growing as necessary to accommodate the data.
In Append mode, data is added onto the end of an existing file.
In Random mode, data may be read or written to any record within the file.

Files are opened with either the OPEN or FSOPEN commands. The OPEN command takes a filename, or full path name as a parameter to be used to locate the file.
The FSOPEN command uses a standard System 7 file system spec (FSSPEC) to locate the file. 

In Input, Output or Append mode, data is accessed sequentially by either reading or writing the value of variables (with INPUT# and WRITE#) or as text data (with LINE INPUT # and PRINT#). The End of File condition can be detected in Input mode by use of the EOF( function.

In Random mode data is accessed by record number using PUT# and GET#.

Files are closed by using the CLOSE verb.

The Toolbox	

Crimson Basic has the capability to support all Macintosh Toolbox calls by means of inbuilt definitions of the input and output parameters required.
In order to support calls to the Toolbox interface, Pascal data types are supported. These are :

        Byte         .. an unsigned 8 bit value of type Boolean.
        Word        .. a 16 bit signed Integer.
        Char         .. a string of characters of fixed length.
        Str255     .. a single byte length field followed by a string.

Toolbox calls may be used within any expression and are identified by the compiler by prefixing the name of the toolbox call with an underscore character. eg.

Global MyWindow As Integer
        ..........
        _ShowWindow(MyWindow)

Global Retval As Word
Global Filename As Str255
        ............
        Retval=_OpenResFile(Filename)

Many of the commonly used Toolbox calls are pre-defined within the compiler. Additional ones may be added by using the TDL (Toolbox Definition Language) compiler which is supplied with this package. (see separate section).

Comments	

A comment line is recognised as a line with an * character in the first non space position with a line.

Comments may be added after a statement following an ' character. eg.

        A=b+c*d   ' this is a comment

Menus	

The Macintosh environment supports a single menu for the entire application unlike some other systems, which have a separate menu for each window.

To create a menu, use the INITMENU command, which sets up a new menu bar with an Apple menu within it, with a menu_id of 128.

If you wish to add an 'About' item to the Apple menu, use the ABOUTMENU function. For example :

AboutId=AboutMenu("About My Application")

.. creates a menu item under the Apple menu with the caption "About My Application" and assigns its menu item id to the variable AboutId.

Normally, when the user selects the About menu item your application should display a message box containing brief details of your application as shown in the example below.

To add a menu to the menu bar, use the ADDMENU function. e.g

FileMenu=AddMenu("File")

.. adds a new menu to the menu bar with a caption of "File" and assigns the menu id of this menu to the variable FileMenu.

To add a menu item to an existing menu, use the ADDMENUITEM function. e.g.

QuitItem=AddmenuItem(FileMenu,"Quit","Q")

.. adds a menu item with a caption of "Quit" to an existing menu with a menu id contained in the FileMenu variable, assigns a keyboard equivalent of "Q" to the menu item and assigns the value of the menu item id to the variable QuitItem.

User events associated with menus are reported to the application via the OnMenu event. OnMenu events are reported to the form which is currently Active (in front).
Menu related events are reported to each Form individually as the context of a menu item is likely to vary from form to form (for example, the processing associated with "Quit" may well be different from form to form).
e.g.

    Procedure Form1.OnMenu(menu_id,menu_item_id)
    Parameter menu_id As Integer
    Parameter menu_item_id As Integer
    Local WhichButton As Integer
      Do Case
        Case menu_id=128                   ' Apple Menu
          If menu_item_id=AboutId
            WhichButton=MsgBox("My Application is Great","OK","")
          Endif
        Case menu_id=FileMenu             ' File Menu
          Do Case
        Case menu_item_id=QuitItem   ' Quit menu item
          End
        Case menu_item_id=  etc.
      Endcase
    Endcase
    Return

Different forms will require different menu items to be available for the user to select (enabled or disabled). The ENABLEMENU and DISABLEMENU commands are provided for this purpose. 

The DISABLEMENU command sets a menu or menu item to a disabled status (with dimmed appearance) and makes it impossible to select this item. e.g.

    DisableMenu FileMenu,QuitItem

The ENABLEMENU command has the opposite effect and enables the item.

To ensure that the menu reflects the desired menu settings appropriate to the currently active form, the forms GotFocus event may be used in applications which have more than one form. e.g.

    Procedure Form1.GotFocus()
      DisableMenu FileMenu,QuitItem
      EnableMenu FileMenu,NewItem
    Return

The GotFocus event will be fired whenever the user clicks on a form thus making this form the current form.

The ERR variable	

The ERR variables is set after a file I/O operation.

Negative values are as defined in the Inside Macintosh Files volumes.

The positive values reported are :
    100 - Invalid file number
    101 - Invalid data found by INPUT#
    102 - File I/O operation is inconsistent with open mode
    103 - Invalid record number in PUT or GET

The Console	

The console provides a method of providing keyboard input and output facilities to the user although the use of Forms is much prefered. The Console should be used only for debugging purposes.
A Console window is opened with the OPEN CONSOLE command.
The PRINT command will output text to the console (and open the console if it is not already open).
The CLS command will clear the contents of the console.
The CLOSE CONSOLE command will close a console.
The INKEY command waits for keyboard input within the console and continues program execution after a key is pressed.